3D Graphics Programming with QuickDraw 3D 1.5.4

Creating and Manipulating Rotate-About-Axis Transforms

QuickDraw 3D provides routines that you can use to create and manipulate rotate-about-axis transforms. An rotate-about-axis transform rotates an object about an arbitrary axis in space by a specified number of radians. You can use macros to convert radians to degrees if you prefer to work with degrees instead of radians. See the chapter "Mathematical Utilities" for more information.

Q3RotateAboutAxisTransform_New

You can use the Q3RotateAboutAxisTransform_New function to create a new rotate-about-axis transform.



 
TQ3TransformObject Q3RotateAboutAxisTransform_New (

                     const TQ3RotateAboutAxisTransformData *data);

data: A pointer to a TQ3RotateAboutAxisTransformData structure.

DESCRIPTION

The Q3RotateAboutAxisTransform_New function returns, as its function result, a reference to a new transform object of type kQ3TransformTypeRotateAboutAxis using the data passed in the data parameter. The data you pass is copied into internal QuickDraw 3D data structures. If QuickDraw 3D cannot allocate memory for those structures, Q3RotateAboutAxisTransform_New returns the value NULL .

Q3RotateAboutAxisTransform_Submit

You can use the Q3RotateAboutAxisTransform_Submit function to submit a rotate-about-axis transform without creating an object or allocating memory.



 
TQ3Status Q3RotateAboutAxisTransform_Submit (

                     const TQ3RotateAboutAxisTransformData *data, 

                     TQ3ViewObject view);

data: A pointer to a TQ3RotateAboutAxisTransformData structure.
view: A view.

DESCRIPTION

The Q3RotateAboutAxisTransform_Submit function pushes the rotate-about-axis transform specified by the data parameter onto the view transform stack of the view specified by the view parameter. The function returns kQ3Success if the operation succeeds and kQ3Failure otherwise.

SPECIAL CONSIDERATIONS

You should call this function only in a submitting loop.

Q3RotateAboutAxisTransform_GetData

You can use the Q3RotateAboutAxisTransform_GetData function to query the private data stored in a rotate-about-axis transform.



 
TQ3Status Q3RotateAboutAxisTransform_GetData (

                     TQ3TransformObject transform, 

                     TQ3RotateAboutAxisTransformData *data);

transform: A rotate-about-axis transform.
data: A pointer to a rotate-about-axis data structure.

DESCRIPTION

The Q3RotateAboutAxisTransform_GetData function returns, in the data parameter, information about the rotate-about-axis transform specified by the transform parameter. You should use Q3RotateAboutAxisTransform_GetData only with transforms of type kQ3TransformTypeRotateAboutAxis .

Q3RotateAboutAxisTransform_SetData

You can use the Q3RotateAboutAxisTransform_SetData function to set new private data for a rotate-about-axis transform.



 
TQ3Status Q3RotateAboutAxisTransform_SetData (

                     TQ3TransformObject transform, 

                     const TQ3RotateAboutAxisTransformData *data);

transform: A rotate-about-axis transform.
data: A pointer to a rotate-about-axis data structure.

DESCRIPTION

The Q3RotateAboutAxisTransform_SetData function sets the rotate-about-axis transform specified by the transform parameter to the data passed in the data parameter. You should use Q3RotateAboutAxisTransform_SetData only with transforms of type kQ3TransformTypeRotateAboutAxis .

Q3RotateAboutAxisTransform_GetOrigin

You can use the Q3RotateAboutAxisTransform_GetOrigin function to get the origin of the axis of rotation of a rotate-about-axis transform.



 
TQ3Status Q3RotateAboutAxisTransform_GetOrigin (

                     TQ3TransformObject transform, 

                     TQ3Point3D *origin);

transform: A rotate-about-axis transform.
origin: On exit, the origin of the axis of rotation of the specified rotate-about-axis transform.

DESCRIPTION

The Q3RotateAboutAxisTransform_GetOrigin function returns, in the origin parameter, the current origin of the axis of rotation of the rotate-about-axis transform specified by the transform parameter.

Q3RotateAboutAxisTransform_SetOrigin

You can use the Q3RotateAboutAxisTransform_SetOrigin function to set the origin of the axis of rotation of a rotate-about-axis transform.



 
TQ3Status Q3RotateAboutAxisTransform_SetOrigin (

                     TQ3TransformObject transform, 

                     const TQ3Point3D *origin);

transform: A rotate-about-axis transform.
origin: The desired origin of the axis of rotation of the specified rotate-about-axis transform.

DESCRIPTION

The Q3RotateAboutAxisTransform_SetOrigin function sets the origin of the axis of rotation for the rotate-about-axis transform specified by the transform parameter to the value passed in the origin parameter.

Q3RotateAboutAxisTransform_GetOrientation

You can use the Q3RotateAboutAxisTransform_GetOrientation function to get the orientation of the axis of rotation of a rotate-about-axis transform.



 
TQ3Status Q3RotateAboutAxisTransform_GetOrientation (

                     TQ3TransformObject transform, 

                     TQ3Vector3D *axis);

transform: A rotate-about-axis transform.
axis: On exit, the orientation of the axis of the specified rotate-about-axis transform. This vector is normalized.

DESCRIPTION

The Q3RotateAboutAxisTransform_GetOrientation function returns, in the axis parameter, the current orientation of the axis of rotation of the rotate-about-axis transform specified by the transform parameter.

Q3RotateAboutAxisTransform_SetOrientation

You can use the Q3RotateAboutAxisTransform_SetOrientation function to set the orientation of the axis of rotation of a rotate-about-axis transform.



 
TQ3Status Q3RotateAboutAxisTransform_SetOrientation (

                     TQ3TransformObject transform, 

                     const TQ3Vector3D *axis);

transform: A rotate-about-axis transform.
axis: The desired orientation of the axis of the specified rotate-about-axis transform. This vector must be normalized.

DESCRIPTION

The Q3RotateAboutAxisTransform_SetOrientation function sets orientation of the axis of rotation for the rotate-about-axis transform specified by the transform parameter to the value passed in the axis parameter.

Q3RotateAboutAxisTransform_GetAngle

You can use the Q3RotateAboutAxisTransform_GetAngle function to get the angle of a rotate-about-axis transform.



 
TQ3Status Q3RotateAboutAxisTransform_GetAngle (

                     TQ3TransformObject transform, 

                     float *radians);

transform: A rotate-about-axis transform.
radians: On exit, the angle, in radians, of the specified rotate-about-axis transform.

DESCRIPTION

The Q3RotateAboutAxisTransform_GetAngle function returns, in the radians parameter, the current angle of rotation (in radians) of the rotate-about-axis transform specified by the transform parameter.

Q3RotateAboutAxisTransform_SetAngle

You can use the Q3RotateAboutAxisTransform_SetAngle function to set the angle of a rotate-about-axis transform.



 
TQ3Status Q3RotateAboutAxisTransform_SetAngle (

                     TQ3TransformObject transform, 

                     float radians);

transform: A rotate-about-axis transform.
radians: The desired angle, in radians, of the specified rotate-about-axis transform.

DESCRIPTION

The Q3RotateAboutAxisTransform_SetAngle function sets the angle of rotation for the rotate-about-axis transform specified by the transform parameter to the value passed in the radians parameter.